-- card: 13037 from stack: in.7
-- bmap block id: 13182
-- flags: 0000
-- background id: 10029
-- name: 


-- part contents for background part 11
----- text -----
© Copyright Apple Computer Co, Inc. 1988
__________________________________________________________

These notes contain information of interest to stack designers and programmers that are not covered in the general HyperCard Version 1.2 Release Notes Stack.  Features visible to the average user are described in the Release Notes Stack.  The HyperCard version 1.2.1 Final Programmer's Notes  include the following:

•  New HyperTalk synonyms.
•  New HyperTalk commands, properties and functions.
•  Using "peeking" for fast script review and editing.
•  Performance improvements in finding text and navigating stacks.
•  User-visible bug fixes.
•  Miscellaneous notes on write-protected media and stacks, and related 
    design considerations.

Briefly, HyperCard 1.2.1 includes the following new features:
•  On locked stacks, HyperCard 1.2.1 distinguishes between user actions and those of HyperTalk scripts.  While users are prevented from making changes to a locked stack (unless the new property userModify is set to true), its scripts can perform most operations.  Changes created in locked stacks are temporary-they disappear when the user leaves the card to which changes have been made.  Specific restrictions imposed by locked media are explained in detail later in this document.
•  Performance and robustness in handling large stacks has been greatly improved.  To take advantage of these improvements, stacks created with older versions of HyperCard should be compacted twice with version 1.2.1.
•  Pictures on cards and backgrounds can now be hidden and shown.  New HyperTalk commands allow stack designers to hide or show art 
(just like buttons or fields) as part of a HyperTalk script.
•  Visual effects work with HyperTalk"s new Unlock Screen command.  Stack designers may now have a button, field or picture appear or disappear with a visual effect rather than just "popping up."
•   Many HyperTalk synonyms, commands and properties have been added or extended.
•  HyperCard 1.2.1 allows fast access to HyperTalk scripts by "peeking."  Users and designers may quickly view and edit scripts.
__________________________________________________________

New HyperTalk Abbreviations:

•  cd = card (get the number of this cd)
•  bg = background (number of cards of this bg)
•  fld = field (hide fld 3)
•  cds = cards (number of cds)
•  bgs = backgrounds (number of bgs)
•  flds = fields (number of flds)
•  btns = buttons (number of btns)
•  second = seconds (wait 1 second)
•  sec = secs (wait 1 sec)
•  tick = ticks (wait 1 tick)
•  pict = picture (hide card pict)
•  grey = gray (dissolve to grey)
__________________________________________________________

New HyperTalk Messages

•  returnInField
This message is sent to the field when the Return key is pressed while there is an insertion point or selection in a field.  If returnInField is not intercepted by a handler and the insertion point or selection is on the last line of the field, HyperCard will check to see if the field has "autoTab" set to true.  If so, HyperCard sends a "tabKey" message to the current field.  If the tabKey message is not intercepted by a handler, the cursor will move to the next field.  If the insertion point or selection is not on the last line of the field, or if autoTab is false, a carriage return will be inserted in the text of the field.

on returnInField -- when the Return key is pressed prevent insertion
  -- of carriage returns anywhere in the field
end returnInField

•  enterInField
The enterInField message is sent to a field when the Enter key is pressed while there is an insertion point or selection in a field.  If enterInField is not intercepted by a handler and the contents of the field have been changed, HyperCard sends a closeField message. 

on enterInField   -- when the enterKey is pressed find the field
  --contents in another stack
 get me
 go to stack "Address"
 find it
end enterInField
__________________________________________________________

New HyperTalk Commands

•  Find Whole "string to be found"
Unlike the general Find command, Find Whole uses both word starts and word endings in finding the chosen text.  Find Whole also uses space characters in the string.  See the HyperCard Version 1.2 Release Notes stack for a description of Find Whole.

•  Find String "string to be found"
Find String finds characters specified in a string, ignoring word boundaries.

Find String "ple"  -- would find the string of characters "ple"

For strings without spaces, it works the same way as Find Chars.  When a string has a space followed by at least three other characters, Find String uses HyperCard"s fast search algorithm.

Find String "ple" offers the same performance as  
Find Chars "ple".

Find String "ple comp"  is much faster because the space and characters in "ple comp" invoke HyperCard"s fast search.  

•  hide picture of <card expression>
This command will hide the card picture specified in the card expression.  For example:

on mouseUp
  hide picture of card 3
end mouseUp

•  hide picture of <background expression>
This command will hide the background picture specified in the background expression.  For example:

on mouseUp
  hide picture of background 3
end mouseUp

•  show picture of <card expression>
This command will show the card picture specified in the card expression.  For example:

on mouseUp
  show picture of card 3
end mouseUp

•  show picture of <background expression>
This command will show the background picture specified in the background expression.  For example:

on mouseUp
  show picture of background 3
end mouseUp

•  hide card picture
This hides the picture on the current card.  For example :

on mouseUp
  hide card picture
end mouseUp

•  show card picture
This shows the picture on the current card.  For example :

on mouseUp
  show card picture
end mouseUp

•  hide background picture
This hides the picture of the current background.  For example :

on mouseUp
  hide background picture
end mouseUp

•  show background picture
This shows the picture of the current background.  For example :

on mouseUp
  show background picture
end mouseUp

•  lock Screen
The lock  Screen command performs the same function as "set lockScreen to true."  For example:

on mouseUp
  lock screen
end mouseUp

•  unlock Screen [with visual effect]
The unlock Screen command performs basically the same function as "set lockScreen to false".   In addition, unlock  Screen can take a single visual effect as an argument.  The visual effect is invoked as the screen is unlocked ("set lockScreen to false" doesn"t invoke visual effects).  

on mouseUp
  set lockScreen to true
  show card button 3
  unlock screen with dissolve slowly
end mouseUp

Note: Visual effects cannot be compounded when using unlock Screen.  The visual effects preceding the unlock Screen command shown below will not be executed until a Go command  is encountered (or until HyperCard has sufficient idle time to flush them).

on mouseUp
  set lockScreen to true
  show card button 3
  visual effect barn door open   -- not invoked by unlock Screen
  visual effect dissolve to black -- not invoked by unlock Screen
  unlock Screen with checkerboard
end mouseUp

In general, visual effects should be as close as possible to the Go command that will use them.  Here is an example of multiple visual effects in a single script:

on mouseUp
 visual effect zoom open -- will execute with the Go command
 go to next card
 lock screen
 show card field 3
 unlock Screen with dissolve -- will work with the unlock Screen
  -- command 
end mouseUp 

•  select <button expression>
Chooses the Button tool and selects the specified button.  For example:

select card button id 78 -- chooses the Button tool and selects the
  -- button
This works the same way as the following:
choose button tool
click at the loc of bkgnd button 3  -- select background button
  -- number 3

This command is especially useful for operations on buttons covered by other objects.  It does not work for hidden buttons and works only when the user level is set to authoring (4) or higher.

•  select <field expression>
Chooses the Field tool and selects the specified field.   This command is especially useful for operations on fields covered by other objects.  It does not work for hidden fields and works only when the user level is set to authoring (4) or higher.

•  select {before|after} <chunk expression> of <field expression>
Selects (highlights) text in a specified field as though the user had clicked or dragged over the specified text.  "Before" or "after" can be used to place an insertion point at a specific location in a field.  A chunk expression can be used to select a range of words or characters in a specified field.  For example:

select word 3 of field 5 -- highlights the third word of background
  -- field 5
select before char 10 of field 3 -- sets the blinking insertion point
  -- between characters 9
  -- and 10 of background field 3
select char 1 to 5 of bkgnd field 1 -- highlights the first five
  -- characters of background field 1
select word 2 to 4 of card field 3 -- highlights the second, third and
  -- fourth words of card field 3
select item 8 of bkgnd field 7 -- highlights the eighth item in card
  -- field 3
  -- remember, items are always separated by commas

If a chunk expression of the form "charStart > charEnd"
 is used, a blinking insertion point will be set.  For example:

select char 10 to 9 of card field 13  -- sets an insertion point between
  -- characters 9 and 10; no text is highlighted

If you "select" past the end of the text in the field, carriage returns will be inserted, and an insertion point will be set after the last return.  For example, if a field has only three lines of text in it, and you select line 5, two carriage returns will be inserted and your cursor will be set on line 5 of the field.

select line 5 of bkgnd field id 8 -- puts the insertion point at line 5
  -- inserting any carriage returns needed to fill empty lines

Chunk expressions may also be used to select text in the message box.  For example:

select word 3 of msg -- highlights the third word of text in the
  -- message box

•  select {before|after} text of <field expression>
Selects all the text in a specified field .  "Before" or "after" can be used to place an insertion point at the beginning or end of the text in a field.  For example:

select after text of card field 7 -- sets the insertion point after the
  -- last character of card field 7 
select text of bkgnd field 3 -- highlights all the text of background
  -- field 3

•  select <me | target>
"Select" may take "me" or "target" as arguments for selecting objects or their contents.  For example:

on mouseUp
  select me -- chooses the appropriate tool and selects the object
  -- when the mouse clicks on it
end mouseUp

on mouseEnter
  select text of me -- selects all the text of a field when the mouse
  -- enters it
end mouseEnter

on mouseUp
  select the target -- chooses the appropriate tool and selects the
  -- object
end mouseUp

•  select empty
Use "select empty" to deselect highlighted text or remove a blinking insertion point.

•  set cursor to <watch | none | hand | arrow | iBeam | plus | cross | busy>
Alternate cursors may be used via the "set cursor to <name or number of cursor>" command, but are shown only for the duration of the handler.  The cursor is always reset to the currently chosen tool (Browse, Button or Field) at idle.

on mouseUp
  set cursor to watch -- show the watch cursor
  repeat until the mouse is down
    go to next card
  end repeat
end mouseUp

set cursor to none -- show the HyperCard transparent cursor
set cursor to hand -- show the HyperCard browse tool cursor 
set cursor to arrow -- show the Macintosh arrow cursor
set cursor to iBeam -- show the I-beam cursor
set cursor to plus -- show the plus cursor
set cursor to cross -- show the cross cursor

The "busy" cursor is HyperCard"s beach ball.  The beach ball will turn 
1/8 each time it is set, so it spins when set inside repeat loops.

on mouseUp
  repeat for 100 times
    set cursor to busy -- show HyperCard"s beach ball cursor (it will
    -- spin)
    add 1 to bkgnd field 1
  end repeat
end mouseUp
__________________________________________________________

New HyperTalk Functions & Properties:

•  cantModify
cantModify is a stack property which prevents users from compacting, deleting or changing the contents of a stack.  See the HyperCard Version 1.2 Release Notes Stack for a detailed description.  For stacks that are not otherwise locked (on a CD-ROM, locked floppy, locked by AppleShare or the Finder), scripts may get and set CantModify.  For example:

set cantModify of stack "MyStack" to true
  -- prevents users from modifying the stack

•  userModify
userModify is a global property which allows the user to type in fields or paint when the stack is locked.  Changes made by the user or script will be discarded upon leaving the card.  userModify is set to false whenever the user leaves a stack; it is ignored when a stack is unlocked. This example allows a user to type in a specific field on a locked stack:

on openField -- user can click in the specified field or press Tab
  set userModify to true
end openField

This next example prevents typing in fields which don't contain the openField handler shown above:

on closeField -- user can click outside the specified field or press Tab
  set userModify to false
end closeField
  -- closeField is only sent when the field contents have been changed

•  cantDelete
Scripts may now get and set the cantDelete property for stacks, backgrounds and cards.  For example:

set cantDelete of this cd to true  -- prevents deletion of the card
set cantDelete of this bg to true  -- prevents deletion of the
  -- background
set cantDelete of this stack to true  -- prevents deletion of the stack

•  showPict
When showPict is true, the card or background picture is visible.  If false, the picture is hidden.  Scripts may get or set showPict.  For example:

get showPict of background 1
if it is "true" then...

•  autoTab
See the HyperCard Version 1.2 Release Notes stack for a functional description.  Scripts may get or set autoTab.  For example:

set autoTab of field 3 to true

•  number of cards of <background expression>
This function returns the number of cards of a specified background.  For example:

get the number of cards of background 3

•  the foundText
Returns the characters enclosed by the box after the Find command has executed.  For example:

find "Will"
put the foundText -- puts "Will" or the whole word it was found
  -- in(e.g. "William") into the msg box

•  the foundChunk
Returns a chunk expression for where the string was found.  For example, if background field 6 contains the phrase "Now is the time," then:

find "Now"
put the foundChunk -- puts "char 1 to 3 of bkgnd field 6" into the
  -- message box

The foundChunk takes the form: char <number> to <number> of <card | bkgnd> field <number>.

•  the foundLine
Returns an expression for  the starting line where the string was found.  For example, if line 2 of card field 3 contains the result of the Find:

find "Tiger"
put the foundLine -- puts "line 2 of card field 3" into the message
  -- box

The foundLine takes the form:  line <number> of <card | bkgnd> field 
<number>.  HyperCard recognizes only lines terminated by a carriage return.  A line that wraps and is displayed as two lines is still one line as far as HyperCard is concerned.

•  the foundField
Returns an expression for the field where the string was found.   For example, if the Find command finds the text in the second line of the third card field:

put the foundField -- puts "card field 3" into the message box

The foundText, foundChunk, foundLine and foundField will be empty when a Find command fails because an empty string is returned.

•  the selectedText
Similar to "the selection," returns the text that is currently highlighted but is not a container into which data can be stuffed.

•  the selectedChunk
Returns a chunk expression for the range of currently highlighted characters.  For example, if a five letter word in card field 9 is selected:

put the selectedChunk -- puts "char 1 to 5 of card field 9" into the
  -- message box.

The expression is of the form: char <number> to <number> of <card | background> field <number>.

•  the selectedLine
Returns an expression for the line where the currently selected text is, using the form: 

line <number> of <card | background> field <number>.

•  the selectedField
Returns an expression for the field where the currently selected text is of the form:

<card | background> field <number>.

•  left of <button expression> <field expression> <window expression>
Returns item 1 of the rect (left, top, right, bottom) of a specified object.  For example:

put left of card button id 456 -- puts the value of the left coordinate
  --  of the rectangle of card button id 456
set left of bkgnd field 5 to 20 -- sets the left coordinate of the
  -- rectangle of background field 5 to 20 pixels from the left edge of 
  -- HyperCard"s window
put left of the card window into MyVar -- puts the left coordinate of
  -- the HyperCard window into the local variable "MyVar"
get left of tool window -- returns the left coordinate of the tool
  -- window

"Set <left | top | right | bottom> of <expression> to <number>"  will move the object so that the specified  parameter is at the specified coordinate.  It is also much faster than using "set loc of <expression>."

HyperCard"s card window uses global coordinates from the Macintosh screen where 0,0 is the top left corner of the screen the menu bar is in.  HyperCard windows  (card, message, tool and pattern) and objects 
(button, field) and the Loc (mouseLoc, clickLoc)  use local coordinates based on HyperCard"s window where 0,0 is the top left corner of HyperCard"s card window.  HyperCard buttons and fields set with negative coordinates are preserved, but cannot be seen or get mouse clicks.

•  top of <button expression> <field expression> <window expression>
Returns item 2 of the rect of a specified object. 

•  right of <button expression> <field expression> <window expression>
Returns item 3 of the rect of a specified object. 

•  bottom of <button expression> <field expression> <window expression>
Returns item 4 of the rect of a specified object. 

•  topLeft of <button expression> <field expression> <window expression>
Returns items 1 and 2 of the rect (l, t, r, b) of a specified object.  This is the top left corner of the object. 

•  bottomRight of <button expression> <field expression> <window expression>
Returns items 3 and 4 of the rect of a specified object.  This is the  bottom right corner of the object. 

•  botRight of <button expression> <field expression> <window expression>
botRight is an abbreviation for bottomRight.

•  width of <button expression> <field expression> <window 
expression>
Returns the width of the specified object.  For example:

put width of card button id 456 -- puts the width of card button 
  -- id 456
set width of bkgnd field 5 to 90 -- sets the width of background 
  --  field 5 to 90 pixels
put width of the card window into ABC -- puts the width of
  -- HyperCard"s window into the local variable "ABC"

When the script changes the width of the specified object, HyperCard preserves the loc (center coordinate) of the object, divides the specified width by 2, sets the left to the dividend and sets the right to (left + the specified width).  For example:

get the width of card button 18 -- put the width of the button into it
set width of card button 18 to it + 20  
-- set left to (item 1 of loc - ((it + 20)/2))

When the width of a button or field is changed by an odd amount, HyperCard rounds the dividend down and adds the remainder (1) to the right coordinate.
When the width of a button or field equals 0 or goes negative, the object continues to exist, but cannot be seen or get mouse clicks.

•  height of <button expression> <field expression> <window expression>
Returns the height of the specified object.
When the script changes the height of the specified object, HyperCard preserves the loc (center coordinate) of the object, divides the specified height by 2, sets the top to the dividend and sets the bottom to (top + the specified height).  For example:

get the height of bkgnd field 11 -- put the height of the field into it
set width of bkgnd field 11 to it + 36
  -- set top to (item 2 of loc - ((it+36)/2))

When the height of a button or field is changed by an odd amount, HyperCard rounds the dividend down and adds the remainder (1) to the bottom coordinate.
When the height of a button or field equals 0 or goes negative, the object continues to exist, but cannot be seen or get mouse clicks.
Neither the height nor width of HyperCard"s window objects (card, message, tools, pattern) can be changed.

•  the screenRect
Returns the rect of the screen being used (left, top, right, bottom) in global coordinates.  When there is more than one monitor, the function returns values for the screen HyperCard"s menu bar is in.

•  the long version [of HyperCard]
Returns the HyperCard version number in the standard Macintosh version resource (see Inside Macintosh for explanations of the format).  In HyperCard 1.2.1:

put the long version  -- puts "01208000" into the message box.

•  the version of <stack expression>
Returns a five item string listing:
1.  the version of HyperCard which created the stack.
2.  the version of HyperCard last used to compact the stack.
3.  the oldest version of HyperCard which changed the stack since it was last compacted.
4.  the version of HyperCard which last changed the stack.
5.  most recent modification date of the stack (in seconds)
Note:  This item is only updated when the stack is closed, not as changes are made.  To confirm a change to the modification date, leave the stack, then reopen it and check item 5 of the long version of the stack.
Items 1 to 4  will be set to 00000000 if the version of HyperCard is less than 1.2.1.
For a stack created with HyperCard version 1.1, then edited and compacted with version 1.2.1 things would look something like this:
put the version of stack "old stack" -- would put
  --"00000000,01208000,01208000,01208000,2660687462"
  -- into the message box
Scripts can convert item 5 into a date and time to determine when the stack was last modified, or check items 1 through 4 to find out whether it had been created, changed or compacted with a version of HyperCard older than 1.2.1.
__________________________________________________________

New HyperTalk Operator:

•  within
Takes the form: <point expression> is {not} within <rect expression> and tests whether a point is within a specific rectangle.  For example:

on mouseUp
  -- tests the mouseLoc and beeps if it is not inside the button rect
  wait until the mouseLoc is not within rect of me
  repeat until the mouseLoc is within rect of me
    beep
  end repeat
end mouseUp

 CONTINUED on next card

-- part contents for background part 17
----- text -----
HyperCard v1.2.1 final programmer's notes • part 1

-- part contents for background part 18
----- text -----



• by
Mike Holm

-- part contents for background part 19
----- text -----
volume 1 •  number  7  •  card 8  •